<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>PF: Runtime Options</title>
<link rev="made" href="mailto:www@openbsd.org">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="resource-type" content="document">
<meta name="description"   content="the OpenBSD FAQ page">
<meta name="keywords"      content="openbsd,faq,pf">
<meta name="distribution"  content="global">
</head>

<!--
Copyright (c) 2003-2007 Joel Knight <enabled@myrealbox.com>

Permission to use, copy, modify, and distribute this documentation for
any purpose with or without fee is hereby granted, provided that the
above copyright notice and this permission notice appear in all copies.

THE DOCUMENTATION IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES WITH REGARD TO THIS DOCUMENTATION INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS DOCUMENTATION
-->

<body bgcolor="#ffffff" text="#000000">
<!-- Passes validator.w3.org, please keep it this way;
please, use a max of 72 chars per line -->

<a href="../../index.html">
<img alt="[OpenBSD]" height=30 width=141 src="../../images/smalltitle.gif" border="0">
</a>
<p>
[<a href="shortcuts.html">Previous: Shortcuts For Creating Rulesets</a>]
[<a href="index.html">Contents</a>]
[<a href="scrub.html">Next: Scrub (Packet Normalization)</a>]

<p>
<h1><font color="#e00000">PF: Runtime Options</font></h1>

<hr>

<p>
Options are used to control PF's operation. Options are specified in
<tt>pf.conf</tt> using the <tt>set</tt> directive.

<p>
<b><font color="#ff0000">NOTE:</font></b> In OpenBSD 3.7 and later, the
behavior of runtime options has changed.
Previously, once an option was set it was never reset to its default
value, even if the ruleset was reloaded.
Starting in OpenBSD 3.7, whenever a ruleset is loaded, the runtime
options are reset to default values before the ruleset is parsed.
Thus, if an option is set and is then removed from the ruleset and the
ruleset reloaded, the option will be reset to its default value.

<a name="block-policy"></a>
<p>
<dl>
<dt><tt>set block-policy <i>option</i></tt><br>
<dd>Sets the default behavior for <a href="filter.html">filter</a> rules
that specify the <tt>block</tt> action.
<ul>
<li><tt>drop</tt> - packet is silently dropped.
<li><tt>return</tt> - a TCP RST packet is returned for blocked TCP
packets and an ICMP Unreachable packet is returned for all others.
</ul>
<dd>Note that individual filter rules can override the default response.
The default is <tt>drop</tt>.
</dl>

<a name="debug"></a>
<p>
<dl>
<dt><tt>set debug <i>option</i></tt><br>
<dd>Set pf's debugging level.
<ul>
<li><tt>none</tt> - no debugging messages are shown.
<li><tt>urgent</tt> - debug messages generated for serious errors.
<li><tt>misc</tt> - debug messages generated for various errors (e.g.,
to see status from the packet normalizer/scrubber and for state creation
failures).
<li><tt>loud</tt> - debug messages generated for common conditions
(e.g., to see status from the passive OS fingerprinter).
</ul>
<dd>The default is <tt>urgent</tt>.
</dl>

<a name="fingerprints"></a>
<p>
<dl>
<dt><tt>set fingerprints <i>file</i></tt><br>
<dd>Sets the file to load operating system fingerprints from. For use
with <a href="filter.html#osfp">passive OS fingerprinting</a>.
The default is <tt>/etc/pf.os</tt>.

</dl>

<a name="limit"></a>
<p>
<dl>
<dt><tt>set limit <i>option value</i></tt><br>
<dd>Set various limits on pf's operation.
<ul>
<li><tt>frags</tt> - maximum number of entries in the memory pool used
for packet reassembly (<a href="scrub.html">scrub</a> rules). Default
is 5000.
<li><tt>src-nodes</tt> - maximum number of entries in the memory pool
used for tracking source IP addresses (generated by the 
<tt>sticky-address</tt> and <tt>source-track</tt> options).
Default is 10000.
<li><tt>states</tt> - maximum number of entries in the memory pool used
for state table entries (<a href="filter.html">filter</a> rules that
specify <tt>keep state</tt>). Default is 10000.
<li><tt>tables</tt> - maximum number of
<a href="tables.html">tables</a> that can be created.
The default is 1000.
<li><tt>table-entries</tt> - the overall limit on how many addresses can
be stored in all tables.
The default is 200000.
If the system has less than 100MB of physical memory, the default is
set to 100000.
</ul>
</dl>

<a name="loginterface"></a>
<p>
<dl>
<dt><tt>set loginterface <i>interface</i></tt><br>
<dd>Sets the interface for which PF should gather statistics such as bytes
in/out and packets passed/blocked. Statistics can only be
gathered for <i>one</i> interface at a time. Note that the
<tt>match</tt>, <tt>bad-offset</tt>, etc., counters and the state table
counters are recorded regardless of whether <tt>loginterface</tt> is set
or not.
To turn this option off, set it to <tt>none</tt>.
The default is <tt>none</tt>.
</dl>

<a name="optimization"></a>
<p>
<dl>
<dt><tt>set optimization <i>option</i></tt><br>
<dd>Optimize PF for one of the following network environments:
<ul>
<li><tt>normal</tt> - suitable for almost all networks.
<li><tt>high-latency</tt> - high latency networks such as satellite
connections.
<li><tt>aggressive</tt> - aggressively expires connections from the state
table. This can greatly reduce the memory requirements on a busy
firewall at the risk of dropping idle connections early.
<li><tt>conservative</tt> - extremely conservative settings. This avoids
dropping idle connections at the expense of greater memory utilization
and slightly increased processor utilization.
</ul>
<dd>The default is <tt>normal</tt>.
</dl>

<a name="ruleset-optimization"></a>
<p>
<dl>
<dt><tt>set ruleset-optimization <i>option</i></tt>
<dd>Control operation of the PF ruleset optimizer.
<ul>
<li><tt>none</tt> - disable the optimizer altogether.
<li><tt>basic</tt> - enables the following ruleset optimizations:
	<ol>
	<li>remove duplicate rules
	<li>remove rules that are a subset of another rule
	<li>combine multiple rules into a table when advantageous
	<li>re-order the rules to improve evaluation performance
	</ol>
<li><tt>profile</tt> - uses the currently loaded ruleset as a feedback
profile to tailor the ordering of quick rules to actual network traffic.
</ul>
<dd>Starting in OpenBSD 4.2, the default is <tt>basic</tt>.
See
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=pf.conf&amp;sektion=5&amp;manpath=OpenBSD+4.3"
>pf.conf(5)</a> for a more complete description.
</dl>

<a name="skip"></a>
<p>
<dl>
<dt><tt>set skip on <i>interface</i></tt><br>
<dd>Skip <i>all</i> PF processing on <tt><i>interface</i></tt>.
This can be useful on loopback interfaces where filtering,
normalization, queueing, etc, are not required.
This option can be used multiple times.
By default this option is not set.
</dl>

<a name="state-policy"></a>
<p>
<dl>
<dt><tt>set state-policy <i>option</i></tt><br>
<dd>Sets PF's behavior when it comes to 
keeping state.
This behavior can be overridden on a per rule basis.
See <a href="filter.html#state">Keeping State</a>.
<ul>
<li><tt>if-bound</tt> - states are bound to the interface they're
created on. 
If traffic matches a state table entry but is not crossing the interface
recorded in that state entry, the match is rejected. 
The packet must then match a filter rule or will be dropped/rejected
altogether.
<li><tt>floating</tt> - states can match packets on any interface.
As long as the packet matches a state entry and is passing in the same
direction as it was on the interface when the state was created, it does
not matter what interface it's crossing, it will pass. 
</ul>
<dd>The default is <tt>floating</tt>.
</dl>

<a name="timeout"></a>
<p>
<dl>
<dt><tt>set timeout <i>option value</i></tt><br>
<dd>Set various timeouts (in seconds).
<ul>
<li><tt>interval</tt> - seconds between purges of expired states and
packet fragments.
The default is <tt>10</tt>.
<li><tt>frag</tt> - seconds before an unassembled fragment is expired.
The default is <tt>30</tt>.
<li><tt>src.track</tt> - seconds to keep a
<a href="filter.html#stateopts">source tracking</a> entry in memory
after the last state expires.
The default is <tt>0</tt> (zero).
</ul>
</dl>

<p>
Example:
<p>
<table border=0 width="650">
<tr><td nowrap bgcolor="#EEEEEE">
<pre>
set timeout interval 10
set timeout frag 30
set limit { frags 5000, states 2500 }
set optimization high-latency
set block-policy return
set loginterface dc0
set fingerprints "/etc/pf.os.test"
set skip on lo0
set state-policy if-bound
</pre>
</td></tr>
</table>


<p>
[<a href="shortcuts.html">Previous: Shortcuts For Creating Rulesets</a>]
[<a href="index.html">Contents</a>]
[<a href="scrub.html">Next: Scrub (Packet Normalization)</a>]

<p>
<hr>
<a href="index.html"><img height="24" width="24" src="../../images/back.gif" border="0" alt="[back]"></a> 
<a href="mailto:www@openbsd.org">www@openbsd.org</a>
<br>
<small>$OpenBSD: options.html,v 1.19 2008/07/28 17:13:02 wcmaier Exp $</small>

</body>
</html> 
